DEFINE-QT-WRAPPERS (qt-library &rest what)

Defines Lisp methods for all Qt methods/signals/slots of given library.
(See example Qt_EQL/trafficlight/).
  (define-qt-wrappers *c++*)        ; generate wrappers (see "Qt_EQL/")
  (define-qt-wrappers *c++* :slots) ; Qt slots only (any of :methods :slots :signals)
  
  (my-qt-function *c++* x y) ; instead of: (! "myQtFunction" (:qt *c++*) x y)


DEFVAR-UI (main-widget &rest variables)

This macro simplifies the definition of UI variables:
  (defvar-ui *main*
    *label*
    *line-edit*
    ...)
  
  ;; the above will expand to:
  
  (progn
    (defvar *label*     (qfind-child *main* "label"))
    (defvar *line-edit* (qfind-child *main* "line_edit"))
    ...)


ENSURE-QT-OBJECT (object)

Returns the qt-object of the given class/struct (see method the-qt-object in example X-extras/CLOS-encapsulation.lisp).
This function is used internally whenever a qt-object argument is expected.


QADD-EVENT-FILTER (object event function)

Convenience function. Adds a Lisp function to be called on a given event type.
If the object argument is NIL, the event will be captured for the whole application.
If the Lisp function returns NIL, the event will be processed by Qt afterwards.

Returns a handle which can be used to remove the filter, see qremove-event-filter.

See also qoverride for QObject::eventFilter(QObject*,QEvent*) and
QObject::installEventFilter(QObject*),
QObject::removeEventFilter(QObject*).

The event class corresponds to the respective event type (no cast needed).
  (qadd-event-filter nil |QEvent.MouseButtonPress| (lambda (object mouse-event) (print object) nil))


QAPP ()

Convenience function returning qApp.


QAPROPOS (&optional search-string class-name)

Finds all occurrencies of the given search string in the given object's meta information.
Constructors are listed under "Methods".
To list the user defined functions of external C++ classes (see Qt_EQL), pass the object instead of the class name.
  (qapropos "html" "QTextEdit")
  (qapropos nil "QWidget")
  (qapropos)
  (qapropos '|toString|)   ; wrapper function symbol
  (qapropos nil *qt-main*) ; see Qt_EQL (QObject derived C++ classes)


QAPROPOS* (&optional search-string class-name)

Similar to qapropos, returning the results as nested list.


QAUTO-RELOAD-C++ (variable library-name)

Linux only.

Extends qload-c++ (see Qt_EQL/).

Defines a global variable (see return value of qload-c++), which will be updated on every change of the C++ plugin (e.g. after recompiling, the plugin will automatically be reloaded, and the variable will be set to its new value).

If you want to be notified on every change of the plugin, set *<variable>-reloaded*. It will then be called after reloading, passing both the variable name and the plugin name.
See qload-c++ for an example how to call plugin functions.
  (qauto-reload-c++ *c++* "eql_cpp")
  
  (setf *c++-reloaded* (lambda (var lib) (qapropos nil (symbol-value var)))) ; optional: set a notifier


QCALL-DEFAULT ()

To use anywhere inside an overridden function (see qoverride).
Calls the base implementation of the virtual Qt method after leaving the function body.

Optionally call the base implementation directly (if you want to do post-processing of the return value).


QCLEAR-EVENT-FILTERS ()

Clears all added event filters.


QCONNECT (caller signal receiver/function &optional slot)

Connects either a Qt signal to a Qt slot, or a Qt signal to a Lisp function.
  (qconnect edit "textChanged(QString)" label "setText(QString)")
  (qconnect edit "textChanged(QString)" (lambda (txt) (print txt)))


QCOPY (object)

Copies object using copy-on-write, if such a constructor is available (non QObject derived classes only).
This function is short for e.g: (qnew "QPixmap(QPixmap)" pixmap)

Note that the returned value will not be garbage collected (analogous to qnew).
  (qcopy pixmap) ; QPen, QBrush, QFont, QPalette, QPixmap, QImage...


QDELETE (object &optional later)
QDEL

Deletes any Qt object, and sets the pointer value to 0. Deleting a widget deletes all its child widgets, too.
If later is not NIL, the function QObject::deleteLater() will be called instead (but note: the object pointer will be set to 0 immediately.)
Returns T if the object has effectively been deleted.

See also qlet for local Qt objects.
  (qdel widget)
  (qdel socket :later)


QDISCONNECT (caller &optional signal receiver/function slot)

Disconnects signals to either Qt slots or Lisp functions. Anything but the caller can be either NIL or omitted.
Returns T if something has effectively been disconnected.
  (qdisconnect edit "textChanged(QString)" label "setText(QString)")
  (qdisconnect edit "textChanged(QString)")
  (qdisconnect edit nil label)
  (qdisconnect edit)


QENUMS (class-name &optional enum-name)

Returns the meta enum list of the given class-name and enum-name (see Q_ENUMS in Qt sources).
Omitting enum-name will return all meta enum lists of the class/scope.
  (qenums "QLineEdit" "EchoMode") ; gives '("QLineEdit" ("EchoMode" ("Normal" . 0) ...))
  (qenums "Qt")


QEQL (object1 object2)

Returns T for same instances of a Qt class. Comparing QVariant values will work, too.
To test for same Qt classes only, do:
  (= (qt-object-id object1) (qt-object-id object2))


QESCAPE (string)

Calls QString::toHtmlEscaped().


QEVAL (&rest forms)

Slime mode :repl-hook only (not needed in default Slime mode): evaluate forms in GUI thread. Defaults to a simple progn outside of Slime.


QEXEC (&optional milliseconds)

Convenience function to call QApplication::exec().
Optionally pass the time in milliseconds after which QEventLoop::exit() will be called.
See also qsleep.


QEXIT ()

Calls QEventLoop::exit(), in order to exit event processing after a call to qexec with a timeout.
Returns T if the event loop has effectively been exited.


QFIND-BOUND (&optional class-name)

Finds all symbols bound to Qt objects, returning both the Qt class names and the respective Lisp variables.
Optionally finds the occurrencies of the passed Qt class name only.
  (qfind-bound "QLineEdit")


QFIND-BOUND* (&optional class-name)

Like qfind-bound, but returning the results as list of conses.


QFIND-CHILD (object object-name)

Calls QObject::findChild<QObject*>().
Can be used to get the child objects of any Qt object (typically from a UI, see qload-ui), identified by QObject::objectName().
  (qfind-child *main* "editor")


QFIND-CHILDREN (object &optional object-name class-name)

Calls QObject::findChildren<QObject*>(), returning a list of all child objects matching object-name and class-name.
Omitting the &optional arguments will find all children, recursively.
  (qfind-children *qt-main* nil "LightWidget") ; see Qt_EQL example


QFROM-UTF8 (byte-array)

Returns the byte array (vector of octets) converted using QString::fromUtf8().


QGUI (&optional process-events)

Launches the EQL convenience GUI.
If you don't have an interactive environment, you can pass T to run a pseudo Qt event loop. A better option is to start the tool like so:
eql5 -qgui, in order to run the Qt event loop natively.


QID (name)

Returns the internally used ID of the object name. Non QObject classes have negative ids.
  (qid "QWidget")


QINVOKE-METHOD (object function-name &rest arguments)
QFUN

Calls any of Qt methods, slots, signals. Static methods can be called by passing the string name of an object.

The most convenient way of calling Qt methods is to use the wrapper functions (see alternative 2 below), which allows for tab completion, showing all possible candidates in case of ambiguous type lists (overloaded methods). Additionally, static functions are shown as one symbol (easily catching the eye).

(Optionally you can pass the argument types (as for qconnect and qoverride), which may result in better performance, but only in some edge cases.)
  (qfun item "setText" 0 "Some objects are EQL.")
  (qfun "QDateTime" "currentDateTime")            ; static method
  (qfun slider "valueChanged" 10)                 ; emit signal
  
  ;; alternative 1: (macro '!')
  
  (! "setText" item 0 "Some objects are EQL.")
  (! "currentDateTime" "QDateTime")
  (! "valueChanged" slider 10)
  
  ;; alternative 2: (wrapper functions)
  
  (|setText| item 0 "Some objects are EQL.")
  (|currentDateTime.QDateTime|)
  (|valueChanged| slider 10)


QINVOKE-METHOD* (object cast-class-name function-name &rest arguments)
QFUN*

Similar to qinvoke-method, additionally passing a class name, enforcing a cast to that class.
Note that this cast is not type safe (the same as a C cast, so dirty hacks are possible).

Note: using the (recommended) wrapper functions (see qfun), casts are applied automatically where needed.
  (qfun* graphics-text-item "QGraphicsItem" "setPos" (list x y)) ; multiple inheritance problem
  (qfun* event "QKeyEvent" "key")                                ; not needed with QADD-EVENT-FILTER
  
  ;; alternatively:
  
  (! "setPos" ("QGraphicsItem" graphics-text-item) (list x y))
  (! "key" ("QKeyEvent" event))
  
  ;; better/recommended:
  
  (|setPos| graphics-text-item (list x y))


QINVOKE-METHOD+ (object function-name &rest arguments)
QFUN+

Use this variant to call user defined functions (declared Q_INVOKABLE), slots, signals from external C++ classes.

In order to call ordinary functions, slots, signals from external C++ classes, just use the ordinary qfun.
  (qfun+ *qt-main* "foo") ; see Qt_EQL
  
  ;; alternatively:
  
  (! "foo" (:qt *qt-main*))


QINVOKE-METHODS (object &rest functions)
QFUNS

A simple syntax for nested qfun calls.
  (qfuns object "funA" "funB" "funC")      ; expands to: (qfun (qfun (qfun object "funA") "funB") "funC")
  (qfuns object ("funA" 1) ("funB" a b c)) ; expands to: (qfun (qfun object "funA" 1) "funB" a b c)
  (qfuns "QApplication" "font" "family")
  (qfuns *table-view* "model" ("index" 0 2) "data" "toString")
  
  ;; alternatively:
  
  (! ("funC" "funB" "funA" object))
  (! (("funB" a b c) ("funA" 1) object))
  (! ("family" "font" "QApplication"))
  (! ("toString" "data" ("index" 0 2) "model" *table-view*))
  
  ;; using wrapper functions, the above reads:
  
  (|funC| (|funB| (|funA| object)))
  (|funB| (|funA| object 1) a b c)
  (|family| (|font.QApplication|))
  (|toString| (|data| (|index| (|model| *table-view*) 0 2)))


QLATER (function)

Convenience macro: a qsingle-shot with a 0 timeout.
This will call function as soon as the Qt event loop is idle.
  (qlater 'delayed-ini)


QLET (((variable-1 expression-1) (variable-2 expression-2) ...) &body body)

Similar to let* (and to local C++ variables).

Creates temporary Qt objects, deleting them at the end of the qlet body.
If expression is a string, it will be substituted with (qnew expression), optionally including constructor arguments.

This macro is convenient for e.g. local QPainter objects, in order to guarantee C++ destructors being called after leaving a local scope.
  (qlet ((painter "QPainter"))
    ...)
  
  (qlet ((reg-exp "QRegExp(QString)" "^\\S+$"))
    ...)


QLOAD (file-name)

Convenience function for Slime (or when loading EQL files from an ECL thread).
Loading files that create many Qt objects can be slow on the Slime REPL (many thread switches).
This function reduces all thread switches (GUI related) to a single one.


QLOAD-C++ (library-name &optional unload)

Loads a custom Qt/C++ plugin (see Qt_EQL/).
The library-name has to be passed as path to the plugin, without file ending.

This offers a simple way to extend your application with your own Qt/C++ functions.
The plugin will be reloaded (if supported by the OS) every time you call this function (Linux: see also qauto-reload-c++).
If the unload argument is not NIL, the plugin will be unloaded (if supported by the OS).
  (defparameter *c++* (qload-c++ "eql_cpp")) ; load (Linux: see also QAUTO-RELOAD-C++)
  
  (qapropos nil *c++*)                       ; documentation
  
  (! "mySpeedyQtFunction" (:qt *c++*))       ; call library function (see also DEFINE-QT-WRAPPERS)


QLOAD-UI (file-name)

Calls a custom QUiLoader::load() function, loading a UI file created by Qt Designer. Returns the top level widget of the UI.
Use qfind-child to retrieve the child widgets.
  (qload-ui "my-fancy-gui.ui")


QLOCAL8BIT (string)

Converts a Unicode pathname to a simple ECL base string, using QString::toLocal8Bit() (see QLocale settings).
Depending on the OS (namely Windows), this is necessary if you get a filename from Qt and want to use it in ECL.

See also QUTF8.


QMESSAGE-BOX (x)
QMSG

Convenience function: a simple message box, converting x to a string if necessary.
Returns its argument (just like print).


QML ()

Generates global variables for all QML items with objectName set, see lisp/ui-vars.lisp. Requires the QML app to be running. Will show an error message if objectName is not unique.


QNEW-INSTANCE (class-name &rest arguments/properties)
QNEW

Creates a new Qt object, optionally passing the given arguments to the constructor.
Additionally you can pass any number of property/value pairs.
Please note how you can abbreviate long type lists.
  (qnew "QWidget")
  (qnew "QPixmap(int,int)" 50 50)                                           ; providing constructor types
  (qnew "QLabel" "text" "Readme")                                           ; set properties (any number); can be combined with above
  (qnew "QMatrix4x4(qreal...)" 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4)             ; abbreviate long type lists
  (qnew "QSizePolicy(...)" |QSizePolicy.Expanding| |QSizePolicy.Expanding|) ; will work if type unambiguous, and no properties are passed


QNEW-INSTANCE* (class-name &rest arguments/properties)
QNEW*

Convenience function for the REPL.
Same as qnew, but showing the object immediately (if of type QWidget).


QNULL-OBJECT (object)
QNULL

Checks for a 0 Qt object pointer.


QOBJECT-NAMES (&optional type)

Returns all supported object names. Passing either :q or :n returns only the QObject inherited, or not QObject inherited names, respectively.


QOK ()

Needed to get the boolean ok value in cases like this:
  (! "getFont(bool*)" "QFontDialog" nil)
  
  (|getFont.QFontDialog| nil) ; NIL needed for <bool*>


QOVERRIDE (object name function)

Sets a Lisp function to be called on a virtual Qt method.
To remove a function, pass NIL instead of the function argument.

If you call qcall-default anywhere inside your overridden function, the base implementation will be called afterwards.
Instead of qcall-default you can directly call the base implementation, which is useful if you want to do post-processing of the returned value.
  (qoverride edit "keyPressEvent(QKeyEvent*)" (lambda (ev) (print (|key| ev)) (qcall-default)))


QPROCESS-EVENTS ()

Convenience function to call QApplication::processEvents().


QPROPERTIES (object &optional (depth 1))

Prints all current properties of object, searching both all Qt properties and all Qt methods which don't require arguments (marked with '*').
Optionally pass a depth indicating how many super-classes to include. Pass T to include all super-classes.
  (qproperties (|font.QApplication|))
  (qproperties (qnew "QVariant(QString)" "42"))
  (qproperties *tool-button* 2)                 ; depth 2: both QToolButton and QAbstractButton


QPROPERTIES* (object)

Similar to qproperties, but listing all properties (including user defined ones) of the passed object instance.
This is only useful for e.g. QQuickItem derived classes, which don't have a corresponding C++ class, in order to list all QML properties.
  (qproperties* (qml:find-quick-item "myItem"))


QPROPERTY (object name)
QGET

Gets a Qt property. Enumerator values are returned as int values.
Returns T as second return value for successful calls.
  (qget label "text")


QQUIT (&optional (exit-status 0) (kill-all-threads t))
QQ

Terminates EQL. Use this function to quit gracefully, not ext:quit.

Negative values for exit-status will call abort() instead of normal program exit (e.g. to prevent infinite error message loops in some nasty cases).


QREMOVE-EVENT-FILTER (handle)

Removes the event filter corresponding to handle, which is the return value of qadd-event-filter.
Returns handle if the event filter has effectively been removed.
See also qclear-event-filters.


QREQUIRE (module &optional quiet)

Loads an EQL module, corresponding to a Qt module.
Returns the module name if both loading and initializing have been successful.
If the quiet argument is not NIL, no error message will be shown on failure.

Currently available modules: :help :multimedia :network :quick :sql :svg :webengine :webkit
  (qrequire :network)


QRGB (red green blue &optional (alpha 255))

Constructs a (unsigned-byte 32) value that represents a 32 bit pixel color specified by the red, green, blue and alpha values.


QRUN-ON-UI-THREAD (function &optional (blocking t))
QRUN

Runs function on the UI thread while (by default) blocking the calling thread (if called from main thread, function will simply be called directly).
This is needed to run GUI code from ECL threads other than the main thread.
Returns T on success.

There are 2 reasons to always wrap any EQL function like this, if called from another ECL thread:See also macro qrun*.
  (qrun 'update-view-data)


QRUN-ON-UI-THREAD* (&body body)
QRUN*

Convenience macro for qrun, wrapping body in a closure (passing arguments, return values).
  (qrun* (|setValue| ui:*progress-bar* value))
  
  (let ((item (qrun* (qnew "QTableWidgetItem")))) ; return value(s)
    ...)


QSELECT (&optional on-selected)
QSEL

Allows to select (by clicking) any (child) widget.
The variable qsel:*q* is set to the latest selected widget.

Optionally pass a function to be called upon selecting, with the selected widget as argument.
  (qsel (lambda (widget) (qmsg widget)))


QSENDER ()

Corresponding to QObject::sender(). To use inside a Lisp function connected to a Qt signal.


QSET-COLOR (widget color-role color)

Convenience function for simple color settings (avoiding QPalette boilerplate).
Use QPalette directly for anything more involved.
  (qset-color widget |QPalette.Window| "white")


QSET-NULL (object)

Sets the Qt object pointer to 0. This function is called automatically after qdel.


QSET-PROPERTY (object name value)
QSET

Sets a Qt property. Enumerators have to be passed as int values.
Returns T as second return value for successful calls.
  (qset label "alignment" |Qt.AlignCenter|)


QSIGNAL (name)

Needed in functions which expect a const char* Qt signal (not needed in qconnect).


QSINGLE-SHOT (milliseconds function)

A single shot timer similar to QTimer::singleShot().
  (qsingle-shot 1000 'one-second-later)
  
  (let ((ms 500))
    (qsingle-shot ms (lambda () (qmsg ms))))


QSLEEP (seconds)

Similar to sleep, but continuing to process Qt events.


QSLOT (name)

Needed in functions which expect a const char* Qt slot (not needed in qconnect).


QSTATIC-META-OBJECT (class-name)

Returns the ::staticMetaObject of the given class name.
  (qstatic-meta-object "QEasingCurve")


QSUPER-CLASS-NAME (name)

Returns the super class of an object name, or NIL if the class doesn't inherit another Qt class.
Returns T as second return value for successful calls.
  (qsuper-class-name "QGraphicsLineItem")


QT-OBJECT-? (object)

Returns the specific qt-object of a generic qt-object.
Works for QObject and QEvent inherited classes only.
  (qt-object-? (|parentWidget| widget))
  (qt-object-? (|widget| (|itemAt| box-layout 0)))
  (qt-object-? event)


QT-OBJECT-NAME (object)

Returns the Qt class name.


QUI-CLASS (file-name &optional object-name)

Finds the class name for the given user-defined object name in the given UI file.
Omitting the object name will return the top level class name of the UI.
  (qui-class "examples/data/main-window.ui" "editor") ; returns "QTextEdit"


QUI-NAMES (file-name)

Finds all user-defined object names in the given UI file.
  (qui-names "examples/data/main-window.ui")


QUIC (&optional (file.h "ui.h") (file.lisp "ui.lisp") (ui-package :ui))

Takes C++ code from a file generated by the uic user interface compiler, and generates the corresponding EQL code.
See also command line option -quic.


QUTF8 (string)

Converts a Unicode pathname to a simple ECL base string, using QString::toUtf8().
Depending on the OS (namely OSX, Linux), this is necessary if you get a filename from Qt and want to use it in ECL.

See also QLOCAL8BIT.


QVARIANT-FROM-VALUE (value type-name)

Constructs a new QVariant. This is needed for types that don't have a direct constructor, like QPixmap, or primitive types, like QSize.
  (qvariant-from-value "red" "QColor")


QVARIANT-VALUE (object)

Returns the Lisp value of the QVariant object.


QVERSION ()

Returns the EQL version number as "<year>.<month>.<counter>".
The second return value is the Qt version as returned by qVersion().


TR (source &optional context plural-number)

Macro expanding to qtranslate, which calls QCoreApplication::translate().
Both source and context can be Lisp forms evaluating to constant strings (at compile time).
The context argument defaults to the Lisp file name. For the plural-number, see Qt Assistant.